<!--

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

-->
<html>
<body>
<h1>jDBI 2.0 Documentation</h1>
<ul>
    <li><a href="http://jdbi.codehaus.org/">Home</a></li>
    <li><a href="index.html">Overview</a></li>
    <li><a href="queries.html">Statements and Queries</a></li>
    <li><a href="spring-integration.html">Spring Integration</a></li>
    <li><a href="http://jdbi.codehaus.org/api-2.0/index.html">Javadocs</a></li>
</ul>
<h2>Overview</h2>

<p>
    jDBI provides a convenience interface for SQL operations in Java. It is not intended as an abstraction layer,
    but rather a library which makes the common things easy and the hard things possible, to paraphrase Larry Wall.
</p>

<p>
    The primary entry point for using jDBI is the <a href="../api-2.0/org/skife/jdbi/v2/DBI.html">DBI</a> class. This
    is used to create <a href="../api-2.0/org/skife/jdbi/v2/Handle.html">Handle</a> instances, each of which
    represents a connection to the RDBMS. A Handle wraps a JDBC <code>Connection</code> instance, and makes use of
    that same Connection for all of its operations.
</p>

<p>
    Generally, you will explicitely create statements, queries, and batch operations for working with data in the
    database. Seperate objects are used to represent these things, and they are designed to be used in a somewhat
    literate-programming style. Here is an example:
</p>
<pre><code>
    DBI dbi = new DBI("jdbc:derby:testing");
    Handle handle = dbi.open();
    Query&lt;Something&gt; query = handle.createQuery("select * from something where name like :name")
                                         .bind("name", "Eri%")
                                         .map(Something.class);
    List&lt;Something&gt; rs = query.list();
    handle.close();
</code></pre>
<p>
    This example just exercises the basics of jDBI. We'll explore the details in the remainder of this documentation.
</p>

<h2>
    Creating DBI Instances
</h2>

<p>
    The two most common ways are to pass in the JDBC connection information, the url, username, and password. In this
    case a new connection will be opened using the JDBC <code>DriverManager</code> for each <code>Handle</code>. An
    alternate, and more efficient means, is to pass a <code>DataSource</code> to the <code>DBI</code> constructor.
    This allows for connection pooling in the datasource, which is generally a good thing. If neither of these
    approaches work well, it is possible to provide your own <code>ConnectionFactory</code> implementation which
    will be used to obtain JDBC connections.
</p>

<p>
    A special case exists for using jDBI in Spring where you want to use Spring's transaction management system.
    This case is described more fully in the <a href="spring-integration.html">Spring Integration</a> documentation.
</p>

<h2>A Brief Tour of the Handle</h2>

<p>
    The <code>Handle</code> basically is a connection to the database. A handle wraps a single JDBC connection
    which it uses for all of its work.
</p>

<p>
    The handle is used, primarily, to create various kinds of statements: queries, statements, batches, prepared
    batches, etc. In addition to these, it has a couple convenience methods for the most commons cases -- simple
    statements and queries with positional parameters. The javadocs for the Handle explain these.
</p>

<p>
    The general idiom for working with the database is to create a statement object from the handle. This will usually
    be a SQLStatement or a Query. When you create the statement object you can then configure exactly how you want
    it to work, then call execute(), list(), iterate(), or first() as appropriate.
</p>

<p>
    A handle is not thread-safe, though it can be used in multithreaded code with external synchronization.
</p>
</body>
</html>
